home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / PROGRAMM / DB_CLIPP / 0643B.ZIP / READ.ME < prev    next >
Text File  |  1987-03-11  |  16KB  |  396 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                    dBASE III Debugging Utilities
  8.  
  9.  
  10.                        By Curtis H. Hoffmann
  11.                          Ver 2.0  03-10-87
  12.  
  13.  
  14.    There are currently eight utilities on this disk, with source 
  15. code, designed for helping to debug and speed up any dBASE III or 
  16. III Plus .PRG files.  These utilities are:
  17.  
  18.    DB_BRUTE.COM:  Displays the .DBF file structure and .NDX index
  19.                   key for every .DBF and .NDX file in the current
  20.                   subdirectory.  If INSERT.COM has been used, then
  21.                   DB_BRUTE can link the .NDX files to the associated
  22.                   .DBF files.
  23.  
  24.    DB_FILES.COM:  Follows the tree structure of your .PRG files and
  25.                   links your .NDX files to the associated .DBF files,
  26.                   then prints out the header data for both types of
  27.                   files.
  28.  
  29.    DB_STRCT.COM:  Displays the tree structure of your files, 
  30.                   every variable used or called out in each file, 
  31.                   and flags any loop mismatches (ie - missing ENDIF 
  32.                   statements, or too many ENDDO's)
  33.  
  34.    DB_VARIBS.COM: Shows the variables as they are declared or 
  35.                   first invoked from each file.  Also lists each 
  36.                   variable still active after returning from a 
  37.                   nested file, and then shows all of the variables
  38.                   that have not been RELEASED as well as those 
  39.                   that have not been used.
  40.  
  41.    DB_COMP.COM:   Strips out all leading spaces, blank lines and 
  42.                   comments.  Removes all unnecessary spaces and 
  43.                   reduces all commands and functions to their 
  44.                   four character minimum.  This utility also 
  45.                   expands a condensed file, adding indents for 
  46.                   each DO/IF loop, but all comments from the 
  47.                   original file will be lost.
  48.  
  49.    LISTING.COM:   Allows you to print out date/time stamped listings
  50.                   of your programs, either one at a time, or in batch
  51.                   mode and automate the process.
  52.  
  53.    INSERT.COM:    Takes a particular .NDX file, goes to a section of
  54.                   wasted space in the header, and inserts the name of the
  55.                   associated .DBF file where it can be easily found, but
  56.                   will not affect the operation of the file.
  57.  
  58.    PICKIT.COM:    The complement of INSERT.COM.  Equivalent to 
  59.                   DB_BRUTE, but one .NDX file at a time and displays
  60.                   only to screen.
  61.  
  62.    To run either of these programs, just type the name of the 
  63. desired utility and hit ENTER.
  64.  
  65.    DB_STRCT, DB_FILES and DB_VARIB will ask for the starting .PRG 
  66. filename, the filename you want the output stored to, and whether 
  67. you want to check all of the files in a dBASE tree, or just one 
  68. file.  (See below for DB_FILES.)
  69.  
  70.    DB_COMP will ask for the starting filename, if you want to 
  71. work on all of the files in a tree or just one, and if you want 
  72. to compress or expand those files.
  73.  
  74.    DB_BRUTE and DB_FILES output to printer only.  
  75.  
  76.    INSERT and PICKIT take their parameters from the command line.
  77. for more detail, just type the program name and hit [ENTER].
  78.  
  79.    LISTING can take a filename as a parameter on the command line
  80. (ie LISTING PRINT.ME).  If it is not given a parameter, it will
  81. automatically look for a file named LISTING.DAT in the current
  82. subdirectory.  If not found, it will tell you more about itself.
  83. LISTING.DAT should just be a collection of filenames (with 
  84. extensions) in the order you want them printed out, one filename 
  85. per line.
  86.  
  87. ================================================================
  88.  
  89.    There should also be three supplementary text files in this
  90. .ARC:
  91.  
  92.    READ.ME:      This file.  The master instruction doc.
  93.    INSERT.PRG:   A dBASE III file that demonstrates the use of
  94.                  INSERT.COM to tag a .NDX file when it is first
  95.                  created.  Syntax:
  96.                  DO INSERT WITH "dbf_name", "ndx_name", "ndx_key"
  97.    DB3_HDR.DOC:  An explanation of the .DBF and .NDX header contents
  98.                  and descriptions.  Can be used with any language, not
  99.                  just Turbo Pascal.  Good for creating your own
  100.                  routines, or helping to understand mine.
  101.  
  102. ================================================================
  103.  
  104.    The operation of these utilities is very simple.  What they 
  105. do, and what the output represents, is a little more complex.
  106.  
  107.  
  108.    DB_COMP, DB_FILES, DB_STRCT, and DB_VARIB assume a .PRG extension
  109. on the files they will be working on.  DB_COMP automatically feeds
  110. its output to a file with the same name as the one it is operating on,
  111. and appends a .NEW extension to it.
  112.  
  113. ===============================================================
  114.  
  115.    Theory of operation (this is just a theory, mind you):
  116.  
  117.    In any given set of dBASE program files, you can employ a 
  118. series of IF/ENDIF, DO CASE/ENDCASE, and DO WHILE/ENDDO loops, as 
  119. well as make calls to other .PRG files with a DO <filename> 
  120. command.  The results of the DO <filename> call gives a tree 
  121. structure to the overall program file set.  Some of these utilities 
  122. explore that tree structure as they perform their various 
  123. operations.  However, if you only want to compress, or debug, 
  124. just one file then the search of the tree structure is skipped 
  125. and the selected operations occur normally.
  126.  
  127. Note:
  128.  
  129.    The output has to go somewhere, so you may be asked for an output 
  130. filename.  If you want the output sent directly to a printer, choose
  131.  PRN; to output to screen, type CON.
  132.  
  133. =========
  134.  
  135. DB_STRCT:
  136.  
  137.    The first part of the report shows the tree structure and all 
  138. of the various files as they are invoked in turn.  Note, if you 
  139. call a particular file several times in your program, that 
  140. filename will appear that many times, and in the location of the 
  141. tree that you invoked it.  Also, if a .PRG file is called with a
  142. DO statement but can not be found (ie -- doesn't exist or is a 
  143. typo) then an ALERT message will state the filename and the file
  144. that tried to call it, then continue with the rest of the report.
  145.    The second part of the report shows the variables used or 
  146. called out in each file, printing the files only once each.  At 
  147. the same time, the utility is checking for loop mismatches, too 
  148. many END statements, or missing END statements at the end of each 
  149. file.  A caution statement is printed out as each condition is 
  150. encountered.
  151.  
  152. example of what could be done wrong in a program:
  153.  
  154.    IF A=B
  155.       DO CASE
  156.          CASE F=1
  157.          CASE F=2
  158.       ENDIF        <-- Expecting ENDCASE, found ENDIF
  159.    ENDDO           <-- Expecting ENDIF, found ENDDO
  160. ENDIF
  161. ENDIF              <-- Too many ENDIF statements
  162.  
  163. =========
  164.  
  165. DB_VARIB:
  166.  
  167.    The first part of this report shows each variable as it is 
  168. encountered for the first time, either as a PUBLIC declaration, 
  169. or a straight statement and treated as a local variable.  Either 
  170. way, these variables are attached to the filename it is first 
  171. encountered in, and then printed out as invoked by that file.
  172.    Then, as the end of each file is encountered, the variables 
  173. released from that file are printed out, as well as a list of 
  174. variables still active.  Also, if a variable has been released, 
  175. the next time it is invoked it will be treated as a new variable 
  176. and printed out as such.
  177.    Like DB_STRCT, DB_VARIB will report a .PRG file that is called
  178. but can not be found, and continue with the rest of the report.
  179.    The second part of the report is two lists.  The first list 
  180. shows all of the variables that were invoked but never used -- 
  181. just a waste of memory space.  The second list shows the 
  182. variables declared PUBLIC and never RELEASEd.  These variables 
  183. may create conflicts in other dBASE programs or when the same 
  184. program is run again.
  185.  
  186. =========
  187.  
  188. DB_COMP:
  189.  
  190.    This utility is intended to speed up the operation of your 
  191. dBASE programs, as well as make them more readable if you lose 
  192. your original source listing, or never had one to begin with.
  193.    In compression mode, DB_COMP strips out all unnecessary 
  194. spaces, comments, and blank lines.  It also reduces the command 
  195. and function words to their four-character minimum length.
  196.    In expansion mode, the command and function words are expanded 
  197. to their full length, and the lines are indented to give a 
  198. pretty-print appearance.
  199.  
  200.    NOTE: Ashton-Tate says that compressing your files this way 
  201. will give you a significantly faster program.  Yes and No.
  202.    What happens:  When dBASE first reads a file to execute, it 
  203. has to wade through the spaces and comments to find the actual 
  204. executable code and then read the extra characters in the 
  205. reserved words to find the next operation or operator.  In this 
  206. way, compressing the files will reduce the time that dBASE wastes 
  207. in interpreting what you wrote.
  208.    HOWEVER: dBASE only needs to do this once when it first 
  209. encounters a file.  Afterwards, the file is converted into 
  210. machine code and is now completely optimized.  Because of this, 
  211. you will not see any time savings on highly repetitive loops that 
  212. don't call any other files.
  213.  
  214.    example:                          Is no faster than
  215.  
  216.    DO WHILE A<=1000                  DO WHIL A<=1000
  217.       A=A+1                          A=A+1
  218.       ? 'I am Wasting Time'          ? 'I am Wasting Time'
  219.    ENDDO                             ENDD
  220.  
  221.    So, if you are doing lots of calculations on a datafile, you 
  222. will save more time by the creative use of INDEX and SET 
  223. RELATION than you will by compressing all your files.  
  224.  
  225.    BUT, you will see a significant speed-up in your user 
  226. interfaces and menu screens by compressing those parts of your 
  227. program.
  228.  
  229. ===
  230.  
  231. LISTING:
  232.  
  233.    This has been explained above.  However, if LISTING.DAT is
  234. found, then LISTING will print out every file it is told to,
  235. sequentially, and with form feeds between listings.  At the top
  236. of each listing, it will date and time stamp the output, and 
  237. include the subdirectory it's in.  I did this for the obvious
  238. reasons.  If it's not obvious to you, drop me a note and I'll 
  239. explain further.
  240.  
  241. ===
  242.  
  243. INSERT:
  244.  
  245.    Look the DB3_HDR.DOC, under the section on .NDX files.  You'll
  246. see that the space from byte 280 to 511 is completely wasted. 
  247. dBASE does not use it at all.  And, because Ashton-Tate stupidly
  248. did not give us a way to tell what .DBF file was in use when a .NDX
  249. was created, I wrote this utility.  It takes the .DBF name you give
  250. it and sticks it starting at location 495.  The name will remain
  251. untouched, and will not affect your data, until you recreate the 
  252. index.
  253.  
  254. ===
  255.  
  256. PICKIT:
  257.  
  258.    This utility just looks at 16 bytes starting with location 495 
  259. in a given .NDX and displays what it finds.  If the associated .DBF
  260. file is not in the same subdirectory, it will suggest that this 
  261. index has not yet been tagged.
  262.  
  263. ================================================================
  264.  
  265. Tricks and Suggestions:
  266.  
  267.    Rather than just operate on one file at a time, use the All 
  268. option from the utility menu screens.  These utilities can 
  269. process 20 large dBASE program files in less than 5 minutes on a 
  270. PC XT, with hard disk.  On an AT, the time drops down to 1.5 
  271. minutes.
  272.  
  273.    If you want to operate on a segment of a dBASE tree, rather 
  274. than the entire tree, just type in the name of the file you want 
  275. to start with, and choose all.  The utilities aren't smart enough 
  276. to work backwards up a tree structure if they haven't started 
  277. from the top.
  278.  
  279. example:
  280.  
  281.    Partial output of DB_STRCT
  282.  
  283.    DEFECT--
  284.            MENU1---
  285.                    IN_MENU-
  286.                            INP_1---
  287.                            UP_INP_1
  288.                            UNASSIGN
  289.                    GEN_MENU
  290.                            CALC_1--
  291.                            CALC_2--
  292.                                    OUT_1
  293.                                    OUT_2
  294.                                    OUT_3
  295.                            CALC_3--
  296.                                    OUT_1
  297.                    PROG_LST
  298.  
  299. So, if you just wanted to analyze the input portion of the tree, 
  300. you'd start with IN_MENU:
  301.  
  302.    Partial output of DB_STRCT
  303.  
  304.    IN_MENU-
  305.            INP_1---
  306.            UP_INP_1
  307.            UNASSIGN
  308.  
  309.  
  310.    When you do an index from now on, use something like 
  311. INSERT.PRG instead of a straight index command.  This way, 
  312. troubleshooting or modifying your programs at a later
  313. date will be made easier because you'll know what .DBF file
  314. each .NDX is for.
  315.  
  316.  
  317. BACKUP ALL OF YOUR FILES BEFORE DOING ANYTHING UNUSUAL TO THEM.
  318.    This is just common sense.  I'm not saying that these 
  319. utilities will munch your hard disk or floppies, but it's stupid 
  320. to take chances on any form of new software, commercial or public 
  321. domain.
  322.  
  323. NOTE:
  324.  
  325.    These utilities were written and compiled in Turbo Pascal ver. 
  326. 3.0.  Now, not every PC compatible is 100% compatible with the 
  327. IBM PC (The Zenith Z-100 chokes on Turbo ver 3.0 itself, as well 
  328. as any programs compiled on it).  So, if your machine can not run 
  329. these utilities, just get a copy of Turbo ver 2.0, config it for 
  330. your PC, and recompile the utilities.  I tried to make them as 
  331. generic as possible, so only the GETDIR(0,PATH) command may give 
  332. you any problems.  If it does, just remove it.
  333.  
  334. =================================================================
  335.  
  336.    Statements of stuff.
  337.  
  338.    I'm putting these utilities, and the source code, into the 
  339. public domain, with the following restrictions:
  340.  
  341. 1)   You may make as many copies of these utilities as you want, 
  342. and give them to anyone you want.  Just keep this READ.ME file 
  343. together with the rest of the files.  Among other things, this is 
  344. the documentation and makes life easier for anyone trying to use 
  345. these utilities.
  346.  
  347. 2)   You don't remove my name from any of the files.  I'm vain, I 
  348. admit it, and I want to get as much recognition for this work as 
  349. I can squeeze out of it.  (By the way, have you read my book?  Just
  350. look under Hoffmann in the science fiction section of your local
  351. bookstore.  It came out in Feb.; the title is _Project: Millennium_.)
  352.  
  353. ==========
  354.  
  355. Revision History:
  356.  
  357. 1.0  10-28-86
  358. -    Initial release.  Included DB_STRCT, DB_VARIB, DB_COMP.
  359.  
  360. 2.0  03-10-87
  361. -    Added error checking to DB_STRCT and DB_VARIB to alert user
  362.      that .PRG file is missing from subdirectory.
  363. -    Included INSERT, PICKIT, LISTING, DB_FILES, DB_BRUTE, and
  364.      DB3_HDR.DOC to the archive.
  365.  
  366. =========
  367.  
  368.    I believe in the shareware concept, so if you really like what 
  369. I've done here, any amount would be appreciated, but I think $10 is
  370. reasonable.
  371.  
  372.    However, I really do want to hear from you.  If you have any 
  373. comments, suggestions for future improvements, complaints, or bug 
  374. reports, please write to me and let me know.  Also, if you come 
  375. across someone else that's also written utilities like these, let 
  376. me know.  If they've done better than I have I'd rather use what 
  377. they've written and be able to sit back and be lazy.
  378.  
  379.    If you make any improvements or changes to the source, let me 
  380. know.  This way, the best of all changes will be incorporated in 
  381. the next release.
  382.  
  383.    Further, if you write and tell me what you think of these 
  384. utilities, I'll put you on a mailing list and alert you to any 
  385. improvements I make or someone else suggests.
  386.  
  387.    Write to me:
  388.                    Curtis H. Hoffmann
  389.                    NCR Comten    QE Dept.
  390.                    2700 Snelling Ave. N.
  391.                    St. Paul, Mn.
  392.                    55113
  393.  
  394.    Either way, thanks for looking these files over.
  395.    'dios.
  396.